home *** CD-ROM | disk | FTP | other *** search
/ Gold Medal Software 2 / Gold Medal Software Volume 2 (Gold Medal) (1994).iso / os2 / pmgb32.arj / PMGLOBEX.DOC < prev    next >
Text File  |  1993-06-04  |  21KB  |  509 lines
  1.                                                              PMGlobe 2.18
  2.    PMGlobe -- an OS/2 Globe -- Commands and Macros
  3.    ===============================================
  4.  
  5.    Copyright (c) International Business Machines Corporation, 1991, 1993.
  6.    All rights reserved.  
  7.  
  8.  
  9.    PMGlobe commands, and how they are used
  10.    """""""""""""""""""""""""""""""""""""""
  11.    This document lists the PMGlobe commands that are currently
  12.    implemented.  These may be invoked from a PMGlobe macro (a program
  13.    written in REXX), or directly from the command dialog (which can be
  14.    displayed by pressing Escape while PMGlobe has the focus).  The
  15.    command dialog allows editing of the command, using Insert, Delete,
  16.    Backspace, and Cursor Left/Right; it also has a simple 'retrieve'
  17.    function, controlled by the Cursor Up/Down keys.
  18.  
  19.    To use commands from a macro, edit (perhaps with the OS/2 System
  20.    Editor) a plain ASCII file such as the TEST.PMG supplied with PMGlobe
  21.    and reproduced in part here: 
  22.  
  23.       /* Sample (test) macro */
  24.       /* Get the version information and set a new title */
  25.       'extract version versionb'
  26.       'set title PMGlobe -' version '('versionb'-bit)'
  27.  
  28.       /* Mark and label some chosen cities */
  29.       "mark  51.5     0   label London"
  30.       "mark  37.8  -122.4 label San Francisco"
  31.       "mark -33.7   151.3 label Sydney"
  32.  
  33.    This is a very simple REXX program that consists almost entirely of
  34.    commands (see SPIN.PMG for a more typical macro).  After saving the
  35.    file, it can by run by simply bringing up the PMGlobe command dialog,
  36.    entering the name of the macro, and pressing Enter.
  37.  
  38.    The 'Macros' checkbox on the command dialog means that macros will be
  39.    searched for before commands.  If it isn't checked, the command "macro
  40.    xxxx", where "xxxx" is the name of the macro, will invoke it.
  41.  
  42.    A macro can be called when PMGlobe is first started by specifying
  43.    "MACRO filename" as a parameter to the PMGlobe call, for example: 
  44.  
  45.       "start pmglobe macro mymacro"
  46.  
  47.    Macro names as a parameter or on a command may include an explicit
  48.    drive and path, and if no extension is given then a default file
  49.    extension of ".pmg" is added.
  50.  
  51.    NOTE: all PMGlobe commands should currently be considered
  52.    experimental; the syntax and semantics of any command could change in
  53.    future versions of PMGlobe (if any).  
  54.  
  55.  
  56.    General notes
  57.    """""""""""""
  58.    1.  Angles may be specified in decimal form, such as -30 or +45.5,
  59.        where for latitude and longitude negative implies south of the
  60.        equator or west of Greenwich respectively.  The more usual format
  61.        is also allowed (for example: 52°30'10E) -- details below.  In
  62.        this document, the character "°" is the degree character, encoded
  63.        on IBM PC's as 248 (decimal) or 'F8'x (hexadecimal).  
  64.  
  65.        Angles returned by QUERY or EXTRACT will always be in decimal
  66.        form.  
  67.  
  68.    2.  Times are specified and returned in seconds (with an optional sign
  69.        for relative times).  
  70.  
  71.    3.  Keywords are shown below in capitals; they may be entered in mixed
  72.        or lower case.  
  73.  
  74.    4.  Colors may also be in any case, and (with valid alternative
  75.        spellings in parentheses) must be one of: White Gray (Grey) Black
  76.        Red Green Blue Pink (Magenta) Cyan (Turquoise) Yellow DarkRed
  77.        DarkGreen DarkBlue Purple (DarkPink, DarkMagenta) DarkCyan
  78.        (DarkTurquoise) Brown.  PaleGray (PaleGrey) is also allowed, for
  79.        the Background color only.  The dark colors (from DarkRed onwards)
  80.        cannot be used for Land or Water coloring.  A QUERY or EXTRACT
  81.        will return the first shown name for each color, in uppercase.  
  82.  
  83.    5.  The keyword "CENTER" may also be spelled as "CENTRE", and "COLOR"
  84.        as (or in) a keyword may be spelled "COLOUR".  
  85.  
  86.    6.  It is recommended that long-running macros (especially those that
  87.        use the WAIT command) use the SET TITLE command to change the
  88.        window title to indicate that the macro is running.  The title
  89.        should be restored to its previous value if halted (see
  90.        FASTSPIN.PMG, for example).  Good macros will also allow for
  91.        asynchronous alteration of viewpoint, etc., due to use of the
  92.        pull-down menus.  
  93.  
  94.    7.  Graphics (drawn with the GLINE command) are shown above any grid
  95.        lines, and underneath any markers, clocks, and marks.  Any tracks
  96.        (drawn using the Distance Calculator, or using the TRACK option on
  97.        graphics commands) are drawn immediately above any graphics.
  98.  
  99.  
  100.    Commands in alphabetical order
  101.    """"""""""""""""""""""""""""""
  102.    CLOSE 
  103.  
  104.        Close PMGlobe (as though Close had been selected in the System
  105.        menu).  
  106.  
  107.    EXTRACT items 
  108.  
  109.        Used for obtaining the values of various PMGlobe settings for use
  110.        with a REXX macro.
  111.  
  112.        'Items' is a list of one or more keywords, as given in the QUERY
  113.        and SET commands below. The values of the specified items are
  114.        placed into REXX variables of the same name.  (See above for a
  115.        simple example.) 
  116.  
  117.    GERASE [DRAW|TRACK] 
  118.  
  119.        Erases either all DRAW graphics or all TRACK graphics.  DRAW is
  120.        the default; TRACK is normally only used by PMGlobe, for drawing
  121.        tracks.  
  122.  
  123.    GLINE lat lon [DRAW|TRACK] 
  124.  
  125.        Draws either a DRAW or a TRACK line from the current point to the
  126.        point specified, and then makes the specified point the current
  127.        point. DRAW is the default, and draws the line in the color set by
  128.        DRAWCOLOR. TRACK is normally only used by PMGlobe, for drawing
  129.        tracks, and draws the line in the color set by TRACKCOLOR.
  130.  
  131.        If no current point has been set (by GMOVE) before this command is
  132.        used, latitude 0 and longitude 0 are used.  
  133.  
  134.    GMOVE lat lon [DRAW|TRACK] 
  135.  
  136.        Sets the current point for either DRAW or TRACK graphics.  DRAW is
  137.        the   default, and sets the current point for DRAW graphics.
  138.        TRACK is   normally only used by PMGlobe, and sets the current
  139.        point for TRACK   graphics.  
  140.  
  141.    FONT name [SIZE height] [COLOR color] [FACE facename] 
  142.  
  143.        Defines a font, with nickname 'name'.  SIZE sets the font size
  144.        (total height in points), and FACE specifies an OS/2 outline font
  145.        (e.g., "Helvetica", "Times New Roman", etc.).  If no FACE is
  146.        specified then the default system proportional font and size is
  147.        used, and SIZE is ignored.  The default size for all other fonts
  148.        is 12 points.  See also the additional notes below.
  149.  
  150.        The color for a font is specified using the COLOR keyword and one
  151.        of the colors listed above.  The default color is Yellow.
  152.  
  153.        Fonts may not be redefined.  The default system proportional font
  154.        is predefined with the nickname 'Default'.  
  155.  
  156.    MACRO file [argumentstring] 
  157.  
  158.        Invoke the specified macro, a REXX program.  The macro should be
  159.        in the working directory for the application, or have its path
  160.        specified.  If no filename extension is given, one of ".pmg" is
  161.        added.  The remainder of the command is passed as the argument to
  162.        the macro (accessible in REXX by the PARSE ARG instruction or
  163.        ARG(1) built-in function).
  164.  
  165.        Note:  At the highest level, macros run as a single separate
  166.        thread.  Macros may invoke each other, using the MACRO command, up
  167.        to a depth of ten (other than this, only one macro can be running
  168.        at a time).  All macros that are running will be halted by
  169.        Ctrl-Break, or by selecting 'Halt macro' from the menus or the
  170.        command dialog.  
  171.  
  172.    MARK lat lon DELETE 
  173.  
  174.        or
  175.  
  176.    MARK lat lon [MARKER m] [X x-offset] [Y y-offset] [CLOCK t-offset]
  177.        [LABEL text] 
  178.  
  179.        Delete or add a mark from or to the displayed globe.  Latitude and
  180.        Longitude (lat lon) are always required.  If DELETE is used, the
  181.        mark must have been added before, and is deleted.  If more than
  182.        one mark have the same latitude and longitude then the most
  183.        recently added is deleted.
  184.  
  185.        If DELETE is not used, then a new mark is added.  The point will
  186.        be marked according to the setting of of SET MARKER (default "+")
  187.        at the time of the MARK command, unless overridden by the option
  188.        MARKER.  The value, m, of the marker can be any of ".", "+", "x",
  189.        "X", or "OFF" for various shapes of marker.  "!" may be used for a
  190.        tiny (single-pel) marker.
  191.  
  192.        The color used for a mark is the current drawing color, as set by
  193.        'SET DRAWCOLOR color', at the time of the MARK command.  If none
  194.        was set then White is used.
  195.  
  196.        A mark may have a text associated with it, described by the CLOCK
  197.        and LABEL options.  This text is displayed with the start of the
  198.        baseline at an offset from the mark as determined by the X and Y
  199.        options; the offsets are given in pels, up to 1000, and may be
  200.        positive or negative, or CENTER.  The default X and Y offsets
  201.        (x-offset and y-offset) are +3.  If the text would extend beyond
  202.        the bounds of the square enclosing the globe, then it is shifted
  203.        in order to stay within bounds (if possible).
  204.  
  205.        If CLOCK is specified, t-offset describes the current GMT offset
  206.        of the mark in seconds, and the text begins with the time
  207.        calculated using this.  This time is shown in 24-hour or civil
  208.        format, depending on the setting of CLOCKCIVIL, and is refreshed
  209.        according to the REFRESH setting.  Use the CLOCKDAY setting for an
  210.        additional tomorrow/yesterday indication (+/-).
  211.  
  212.        If LABEL is specified, it must be the last option on the command:
  213.        the remainder of the command, after the keyword LABEL and one
  214.        blank, forms the label part of the text, which follows any clock
  215.        and may be up to 100 characters.
  216.  
  217.        The font used for the text is the current font, as set by 'SET
  218.        FONT nickname', at the time of the MARK command.  If none is set
  219.        then the default system font is used.
  220.  
  221.        Markers, clocks, and labels can be included or excluded as a group
  222.        by using the MARKERS, CLOCKS, and LABELS settings.  None of these
  223.        are shown if the window size is less than or equal to 64 pels in
  224.        either dimension (for example, if the globe is minimized to the
  225.        desktop).  
  226.  
  227.    MESSAGE text 
  228.  
  229.        Display text in a message box.  The message box can be moved, and
  230.        does not inhibit interaction with the globe or distance
  231.        calculator.  The MESSAGE command waits until the "OK" pushbutton
  232.        on the message box is selected or the message box is closed.
  233.        Commands are currently limited to 200 characters, so the longest
  234.        message possible is 192 characters.  
  235.  
  236.    REDRAW [ALL] 
  237.  
  238.        Initiates a redrawing of the Globe.  Normally a REDRAW is
  239.        automatic at the end of a macro or (if the box on the dialog is
  240.        checked) after a command is entered from the command dialog.  The
  241.        REDRAW command is provided for long-running macros.  The command
  242.        does not wait until redrawing is complete.
  243.  
  244.        The ALL option requests that all features of the globe are
  245.        redrawn, including any grid lines and marks (normally only those
  246.        features that have changed since the last draw are drawn).  
  247.  
  248.    QUERY items 
  249.  
  250.        Queries the state of various PMGlobe settings.  'items' is a list
  251.        of one or more keywords.  Currently the result is displayed using
  252.        PMprintf; to see the results the PMprintf console must be active.
  253.        (PMprintf is an IBM developer's tool; if you do not have access to
  254.        this, use the EXTRACT command in a macro, followed by the MESSAGE
  255.        command to display values, etc.)
  256.  
  257.        Any item that can be set by the SET command (see below) may also
  258.        be queried.  The value of any item that may be set or queried may
  259.        also be obtained by a macro, using the EXTRACT command.  PMprintf
  260.        is not needed in order to use these values in a macro.
  261.  
  262.        Valid items are: 
  263.  
  264.        ACTIVE     
  265.            ON if the globe window is the active window, else OFF
  266.  
  267.        CLOCKMARKS 
  268.            number of clocks set using the MARK command
  269.  
  270.        DAYOFFSET  
  271.            time offset due to daylight savings (in seconds), or "UNKNOWN"
  272.  
  273.        DIAMETER   
  274.            globe diameter in pels (0 if unknown)
  275.  
  276.        FONTS      
  277.            number of fonts defined using the FONT command
  278.  
  279.        GMTOFFSET  
  280.            base time offset from GMT (in seconds), or "UNKNOWN"
  281.  
  282.        MARKS      
  283.            number of marks set using the MARK command
  284.  
  285.        SETNAME    
  286.            'application name' for .INI settings (up to 25 characters)
  287.  
  288.        SUNLAT     
  289.            latitude at which sun is overhead (x.xxx), or "UNKNOWN"
  290.  
  291.        SUNLON     
  292.            longitude at which sun is overhead (x.xxx), or "UNKNOWN"
  293.            (multiply by -4 to get time in minutes from solar noon)
  294.  
  295.        VERSION    
  296.            PMGlobe version number
  297.  
  298.        VERSIONB   
  299.            Version bits: always 32 for PMGLOBE2.EXE
  300.  
  301.        ZONEABBREV 
  302.            timezone abbreviation (3 or 4 characters, or "???" if unknown)
  303.  
  304.    SET item newvalue 
  305.  
  306.        Changes the state of various PMGlobe settings.  Item is one of the
  307.        listed keywords.  The value of any item that can be SET can also
  308.        be queried using the QUERY command, or obtained by a macro using
  309.        the EXTRACT command (see above).
  310.  
  311.        Flags (items that are either ON or OFF) can also be set to INVERT,
  312.        which changes the state of the flag from ON to OFF or vice versa.
  313.  
  314.        Valid items are: 
  315.  
  316.        BACKCOLOR  
  317.            set the color of the background (names as given above)
  318.  
  319.        CLOCKCIVIL 
  320.            use 12-hour clock format for any clocks (ON/OFF)
  321.  
  322.        CLOCKDAY   
  323.            add flag (+ for tomorrow, - for yesterday) to clocks (ON/OFF)
  324.  
  325.        CLOCKS     
  326.            display the clocks on marks (ON/OFF)
  327.  
  328.        CROSSHAIR  
  329.            use cross-hair cursor when over globe (ON/OFF)
  330.  
  331.        DESKTOP    
  332.            make PMGlobe the bottommost window (ON/OFF)
  333.  
  334.        DRAWCOLOR  
  335.            set the color for drawing marks and graphics (names as above)
  336.  
  337.        ERRORBOX   
  338.            display command errors in a message box (ON/OFF)
  339.  
  340.        FONT       
  341.            sets the current font, by nickname
  342.  
  343.        GRIDCOLOR  
  344.            set the color of grid lines (names as above)
  345.  
  346.        GRIDLAT    
  347.            grid latitude line frequency (0/10/15/30/90)
  348.  
  349.        GRIDLON    
  350.            grid longitude line frequency (0/10/15/30)
  351.  
  352.        GRIDPOLAR  
  353.            show grid polar circles (ON/OFF)
  354.  
  355.        GRIDTROPIC 
  356.            show grid tropics (ON/OFF)
  357.  
  358.        IDLEDRAW   
  359.            draw map at low (IDLE+1) priority (ON/OFF)
  360.  
  361.        LABELS     
  362.            display the labels on marks (ON/OFF)
  363.  
  364.        LANDCOLOR  
  365.            set the color used for land at its brightest (names as above)
  366.  
  367.        MARGIN     
  368.            percentage border to allow around globe (0->49.999%)
  369.  
  370.        MARKER     
  371.            current default marker (".", "+", "x", "X", or "OFF")
  372.  
  373.        MARKERS    
  374.            display the markers on marks (ON/OFF)
  375.  
  376.        REFRESH    
  377.            current refresh interval (in seconds, max 24 hours)
  378.  
  379.        SHADING    
  380.            '3-D' shading (ON/OFF)
  381.  
  382.        SHOWDRAW   
  383.            show (update) picture of globe as it is calculated (ON/OFF)
  384.  
  385.        STARLIGHT  
  386.            'star' lighting (ON/OFF) -- implies SUNLIGHT ON and SPACE ON
  387.  
  388.        SUNLIGHT   
  389.            'sun' lighting (ON/OFF)
  390.  
  391.        SPACE      
  392.            'earth from space' lighting (ON/OFF) -- implies SUNLIGHT ON
  393.  
  394.        TITLE      
  395.            window and task list title (max 50 characters)
  396.  
  397.        TRACKCOLOR 
  398.            set the color for drawing tracks (names as above)
  399.  
  400.        TWILIGHT   
  401.            degrees of twilight shown (max 18 degrees)
  402.  
  403.        USEROFFSET 
  404.            time to add to real time (seconds, max +/- one year)
  405.  
  406.        VIEWLAT    
  407.            latitude of center of view  (x.xxx)
  408.  
  409.        VIEWLON    
  410.            longitude of center of view (x.xxx)
  411.  
  412.        WATERCOLOR 
  413.            set the color used for lakes and seas (names as above)
  414.  
  415.        The following settings are for development use only; the effect of
  416.        each is not defined: 
  417.  
  418.        DIAG       
  419.            send diagnostic messages to PMprintf (ON/OFF)
  420.  
  421.        DIAGMSG    
  422.            display PM client messages to PMprintf (ON/OFF)
  423.  
  424.        TEST       
  425.            controls certain test functions (ON/OFF)
  426.  
  427.    WAIT [REDRAW] [time] [+time] 
  428.  
  429.        Wait until a redraw is completed, or until a particular
  430.        time-of-day, or for a certain length of time from now.  "time" is
  431.        in hours, with optional minutes and seconds indicated by colons
  432.        (for example, +0:20 would mean "wait for twenty minutes").  If a
  433.        specific time of day is given and is earlier than the current time
  434.        of day, then the next day is assumed.  Multiple times (absolute,
  435.        relative, or mixed) may be specified, and WAIT will return when
  436.        the earliest is reached.  The maximum wait time is 24 hours (+24).
  437.  
  438.        If REDRAW is specified, then a REDRAW is started automatically,
  439.        and WAIT will return when the redraw is complete or any time
  440.        condition specified is met, whichever happens earlier.
  441.  
  442.        Any WAIT is also ended by Ctrl-Break, or by selecting 'Halt macro'
  443.        from the menus or the command dialog.  
  444.  
  445.  
  446.    Changing fonts
  447.    """"""""""""""
  448.    The fonts used for any clocks and labels on the MARK command can be
  449.    changed by first defining a new font (with the FONT command) and then
  450.    making the new font the current font (with the SET FONT command)
  451.    before issuing the MARK command.
  452.  
  453.    The FONT command uses OS/2's facilities for choosing the 'nearest
  454.    outline font'; if no good match is found (for example, no font with
  455.    the specified face name exists) then the default system bitmap font is
  456.    used.
  457.  
  458.    The face name on a font definition should match the OS/2 font name for
  459.    an outline font exactly (for example "Helvetica", not "helvetica").
  460.    It can be difficult to find a list of the fonts available; one way you
  461.    may be able to find one (if you have a printer installed) is to look
  462.    at the font installation panel for the printer driver you are using.
  463.    (Click mouse button 2 on the printer icon, then open Settings. Select
  464.    the Printer Driver page, then click button 2 on the driver icon and
  465.    select Settings again, then Fonts.)  The following should always be
  466.    available: 'Courier', 'Helvetica', 'Times New Roman', and 'Symbol
  467.    Set'.  The first three of these may be followed by 'Bold', 'Italic',
  468.    or 'Bold Italic'.
  469.  
  470.    Example: 
  471.  
  472.       /* ORIGIN.PMG -- Show the origin in a Large font */
  473.       'font classic  size 18  color red  face Times New Roman Italic'
  474.       'set font classic'
  475.       'mark 0 0 y centre label The Origin'
  476.  
  477.  
  478.    Formats allowed for specifying degrees
  479.    """"""""""""""""""""""""""""""""""""""
  480.    A degree value may be specified in in degree-minutes-seconds format,
  481.    or in degree.decimal format.
  482.  
  483.    If the degree value is specifying a latitude or longitude, then it may
  484.    be followed by one of the characters N, S, E, W (in either case), as
  485.    appropriate.  The default is N (North) for latitude and E (East) for
  486.    longitude.  A leading minus sign is allowed in either format, and
  487.    negates the direction implied by any N, E, S, or W.  A leading plus
  488.    sign is also allowed; it has no effect.
  489.  
  490.    No blanks are allowed: the seconds, or seconds and minutes, may be
  491.    omitted, as may be insignificant leading zeros.  The syntax is
  492.    therefore one of: 
  493.  
  494.       [+|-][d]d[o[m]m['[s]s["]]][x]
  495.       [+|-][d]d[.[[d]d]d][x]
  496.  
  497.    where the degree indicator in the first format may be either the
  498.    letter O (either case) or the true degree character (°, ASCII 248 on
  499.    IBM PCs and PS/2s).
  500.  
  501.    Examples (all specifying a negative angle of 12 degrees 30 minutes): 
  502.  
  503.       12°30'S       -12°30         12°30W        -12.5
  504.       12°30'0"S     -12°30'00N    -12.500E        12o30s
  505.  
  506.    --------
  507.  
  508.    Mike Cowlishaw, IBM UK Laboratories
  509.